<html>
<head>
<meta charset="utf-8" />
<title>PostGISRaster --- PostGIS Raster driver</title>
</head>

<body bgcolor="#ffffff">

<h1>PostGISRaster --- PostGIS Raster driver</h1>

<p>PostGIS Raster (previously known as WKT Raster) is the project that
provides raster support on PostGIS. Since September 26st, 2010,
is an official part of PostGIS 2.0+.</p>

<p>This driver was started during the ​Google Summer of Code 2009,
and significantly improved since then.</p>

<p>Currently, the driver provides read-only support to PostGIS Raster data sources.</p>

<h2>Connecting to a database</h2>

<p>To connect to a PostGIS Raster datasource, use a connection string specifying the database name,
with additional parameters as necessary</p>

<pre>
PG:"host='<host>' port:'<port>' dbname='<dbname>' user='<user>' password='<password>' [schema='<schema>'] [table='<raster_table>'] [column='<raster_column>'] [where='<sql_where>'] [mode='<working_mode>']"
</pre>

<p>Note that the string, up to the part starting with "table='" is a libpq-style ​connection string. That means that you can leave out unnecessary fields (like password, in some cases).</p>

<ul>
<li><b>schema</b> - name of PostgreSQL schema where requested raster table is stored.</li>
<li><b>table</b> - name of PostGIS Raster table. The table was created by the raster loader (eg. raster2pgsql utility).</li>
<li><b>column</b> - name of raster column in raster table</li>
<li><b>where</b> - option is used to filter the results of the raster table. Any SQL-WHERE expression is valid.</li>
<li><b>mode</b> - option is used to know the expected arrangement of the raster table. There are 2 possible values
<ul>
    <li><b>mode=1</b> - ONE_RASTER_PER_ROW mode. In this case, a raster table is considered as a bunch of different raster files. This mode is intended for raster tables storing different raster files. It's the default mode if you don't provide this field in connection string.</li>
    <li><b>mode=2</b> - ONE_RASTER_PER_TABLE mode. In this case, a raster table is considered as a unique raster file, even if the table has more than one row. This mode is intended for reading tiled rasters from database.</li>
</ul>
</li>
</ul>

<h3>Additional notes</h3>

<p>If a table stores a tiled raster and you execute the driver with mode=1, each image tile will be considered as a different image, and will be reported as a subdataset. There are use cases the driver can't still work with. For example: non-regular blocked rasters. That cases are detected and an error is raised. Anyway, as I've said, the driver is under development, and will work with more raster arrangements ASAP.</p>

<p>There's an additional working mode. If you don't provide a table name, the driver will look for existing raster tables in all allowed database' schemas, and will report each table as a subdataset.</p>

<p>You must use this connection string's format in all the gdal tools, like gdalinfo, gdal_translate, gdalwarp, etc.</p>

<h2>Examples</h2>

To get a summary about your raster via GDAL use gdalinfo:

<pre>
gdalinfo  "PG:host=localhost port=5432 dbname='mydb' user='postgres' password='secret' schema='public' table=mytable"
</pre>

<p>For more examples, check the PostGIS Raster FAQ section:
<a href="https://postgis.net/docs/RT_FAQ.html#idm28288">​Can I export my PostGIS Raster data to other raster formats?</a></p>

<h2>Credits</h2>

The driver developers

<ul>
<li>Jorge Arévalo (jorgearevalo at libregis.org)</li>
<li>David Zwarg (dzwarg at azavea.com)</li>
<li>Even Rouault (even.rouault at mines-paris.org) </li>
</ul>

<h2>See Also</h2>

<ul>
<li><a href="https://trac.osgeo.org/gdal/wiki/frmts_wtkraster.html">GDAL PostGISRaster driver Wiki<a></li>
<li><a href="https://postgis.net/docs/RT_reference.html">PostGIS Raster documentation</a></li>
</ul>

</body>
</html>
